_______________________________________________________________________ Chapter 2: PADtalk Scripts 13 ________________________________________________________________________ CHAPTER TWO: PADTALK SCRIPTS CONSTRUCTING SCRIPTS In HyperPAD, scripts are written using the Script Editor. In order to access an object's script, the pad's user level must be set to scripting. (See the section on user levels in the HyperPAD User's Guide for additional information.) To access an object's script: 1. Make sure the pad's user level is set to Scripting. 2. Select the object with the Selector tool. In order to access a button or field's script, you must use the Selector tool and select the object. 3. Open the object's Info dialog box from the Objects menu. Depending on the type of object you are working with, select Pad, Bkgnd, Page, Button, or Field Info from the Objects menu. 4. Select the button from the dialog box. The Script Editor will be loaded along with the object's script. _______________________________________________________________________ Chapter 2: PADtalk Scripts 14 ________________________________________________________________________ THE SCRIPT EDITOR The Script Editor is an environment that allows you to edit an object's script and then compile it. It looks like this: 旼컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� � � � **** The Printed Documentation has a picture or screen shot here **** � � � 읕컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� EXITING THE SCRIPT EDITOR: To exit the Script Editor and return to the previous screen, use one of the following methods: 1. Press ESC. If you have made any modifications, you will be asked if you want to save them. 2. Select Cancel from the File menu. Any changes you made will be lost. 3. Select Save and Return from the File menu. This saves any changes and then returns to the pad. LET'S START SCRIPTING: Let's create a very simple script linking a newly created button to the Home pad. (If you are going to do the procedures, you should create a new pad and a new button.) To create a new pad: 1. Set the user level to scripting. (See the section on user levels in the HyperPAD User's Guide.) _______________________________________________________________________ Chapter 2: PADtalk Scripts 15 ________________________________________________________________________ 2. Select the New command from the File menu. 3. Type in the name of your pad and press ENTER. A blank page will be placed on-screen. To create a new button: 1. Set the user level to scripting. 2. Select the Select tool from the Tools menu. 3. Select the New Button command from the Objects menu. A new button will appear on-screen. To go to the button's script: 1. Select Button Info from the Objects menu (or just press ENTER). 2. Select the button (or press ALT+S). First, access the button's script. When the Script Editor loads, you'll see that HyperPAD has already written part of the script for you. Because almost all buttons created in HyperPAD respond to being selected, each button's script, by default, provides an empty select handler. 旼컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� � � � **** The Printed Documentation has a picture or screen shot here **** � � � 읕컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� First, examine the script HyperPAD has provided, line by line: handler select; A handler is a portion of an object's script that defines what happens when a certain message is received. Each handler statement, like the one _______________________________________________________________________ Chapter 2: PADtalk Scripts 16 ________________________________________________________________________ above, names the message the handler responds to (in this case the select message) and must end with a semi-colon. The name determines which message triggers the execution of this handler. For more information on messages see Chapter Ten. begin end; The begin and end statements enclose the list of actions that make up this handler. When the select message is received by this button, the action statements listed between the begin and end statements will be executed. handler select; begin [statements executed when the button is selected] end; Each begin statement must have a corresponding end statement in order for the handler to be valid. A semi-colon must follow the end statement, signifying the end of the handler. The blank line that HyperPAD has left is for the author to complete. In between the begin and end statements, fill in the actions to be taken when this button is selected. In this case, we want the user to change to the next page. To complete the handler, add the following line: go to the next page; HyperPAD does not distinguish between upper and lower case letters - it recognizes go to the next page; and Go To The Next Page; as the same statement. Every PADtalk statement within a begin...end block must end with a semi- colon. You can incorporate numerous commands to execute by inserting them between the begin and end statements. The full handler should resemble the following: handler select; begin go to the next page; end; We have just created a script with one handler that responds to the select message. If the user selects this button (by pressing ENTER or with the mouse) the handler will execute, changing to the next page in the pad. _______________________________________________________________________ Chapter 2: PADtalk Scripts 17 ________________________________________________________________________ Scripts can contain many handlers allowing objects to respond to a variety of messages. For example, the following script responds to three messages: handler select; begin go to the next page; end; handler mouseUp; begin beep; end; handler mouseEnter; begin hide the menu bar; end; WRITING STATEMENTS IN PADTALK Each PADtalk statement ends with a semi-colon. A begin...end block, like in the Pascal languages, is really a single compound statement (that's why there is a semi-colon after the end). PADtalk is a flexible language. It sometimes provides more than one way to perform the same action. For example, the following statements access the next page: go to the next page; go to next page; go next page; go to page (currentPage() + 1); In many PADtalk statements, like the go statement shown above, you can use the word the. The use of this word is optional and has no purpose except to enhance readability of your scripts. (The exception is with the alternate syntax of function calls.) You can add comments to your scripts by enclosing them in curly brackets. Any text within brackets is ignored by the compiler. The following example shows a comment enclosed in brackets. { this is a comment } go to the next page; _______________________________________________________________________ Chapter 2: PADtalk Scripts 18 ________________________________________________________________________ Brackets can enclose many lines, shown in the following example: { this is a comment that takes up two lines } go to the next page; You can also enclose comments within other comments. The following example comments out a few statements that have comments: { go to the next page; { change pages } beep; { emit a sound } answer "Find What?"; { ask user question } } You can add a comment to the end of a line by using two consecutive hyphens (--). The text between the two hyphens and the end of the line is ignored by the compiler. For example: -- this is a comment go to the next page; -- this is a comment too! PADtalk is a verbose language that understands over 400 different words. Before exploring it, become comfortable within the Script Editor. USING THE KEYBOARD Press this key: To: ------------------------------------------------------------------------ UP and DOWN Move up or down one line in a script LEFT and RIGHT To move left or right on a line in a script HOME Go to the beginning of a line CTRL+HOME Go to the beginning of the script END Go to the end of the line CTRL+END Go to the end of the script CTRL+RIGHT or CTRL+LEFT Move forward or backward one word BACKSPACE Delete the previous character DEL Delete the character under the cursor CTRL+Y or CTRL+D Delete the current line CTRL+BACKSPACE Delete the previous word _______________________________________________________________________ Chapter 2: PADtalk Scripts 19 ________________________________________________________________________ Press this key: To: --------------------------------------------------------- SHIFT+ARROWS Select text ESC or CTRL+Q Exit with a check to save changes CTRL+C or CTRL+INS Copy selected text TAB Inserts space up to next tab stop PGUP or MINUS (keypad) Move up one page PGDN or PLUS (keypad) Move down one page CTRL+X or SHIFT+DEL Cut text CTRL+V or SHIFT+INS Paste text CTRL+DEL Delete to the end of the line CTRL+F Find a string CTRL+R Find and replace text CTRL+N Find next occurrence of the string F4 Compile the script, checking for errors F10 Open the menus EDITING A SCRIPT In the Script Editor, you can copy and move blocks of text within a script or even between scripts. Before you can using any of the editing features, you have to select the text you want to perform the operation on. To select text: 1. Place the cursor on the first character of the selection. 2. Hold down SHIFT and use the arrow keys to extend the selection. 3. When you've highlighted the entire selection, release the keys. To use the mouse, place the mouse pointer where you want to begin your selection. Hold down the left mouse button and drag the mouse until you've highlighted the selection. Then, release the mouse button. Once the text is selected, you can copy, cut, or delete it. _______________________________________________________________________ Chapter 2: PADtalk Scripts 20 ________________________________________________________________________ To copy text: 1. Select the text. 2. Select the Copy command from the Edit menu (ALT+E, C). To cut text: 1. Select the text. 2. Select the Cut command from the Edit menu (ALT+E, T). To paste text: 1. Position the cursor where you want to place the text. 2. Select the Paste command from the Edit menu (ALT+E, P). The contents of the clipboard will be inserted in the script. SEARCH AND REPLACE As you become more comfortable with PADtalk, your scripts will become longer and more complex. To reduce the amount of time and effort necessary to locate text, HyperPAD includes Search and Replace commands. To locate a string in a script: 1. Select the Find command from the Search menu (ALT+S, F). The Find dialog box will appear on screen. 2. Type in the string you want to locate and press ENTER. To locate the next instance of a string: 1. First complete the above procedure. 2. Select the Find Next command from the Search menu (ALT+S, N). To keep looking for that string, continue to select the Find Next command. CTRL+N is the shortcut for this command. Sometimes, you may need to replace a string in a script with another. Use the Replace command to locate the instance and replace it with what you've specified. _______________________________________________________________________ Chapter 2: PADtalk Scripts 21 ________________________________________________________________________ To search and replace within a script: 1. Select the Replace command from the Search menu. 2. Enter in the search and replace text, then select: Verify - Allows you to confirm each replacement. Replace - Replace the text and continue. Skip - Continue without replacing the text. Cancel - Stop the procedure. PRINTING SCRIPTS To print the scripts in your pads: 1. Select Printer Setup from the File menu and complete the dialog box so the options conform to your system. If your printer is not listed, select the Generic Printer, or another that your printer can emulate. 2. Select Page Setup from the File menu and make sure the settings are correct. 3. Select the Print command from the File menu. COMPILING SCRIPTS Before HyperPAD can use your scripts, they must first be compiled. HyperPAD compiles and saves your script when you exit the Script Editor. As it compiles, HyperPAD scans the script, checking for syntax errors. HyperPAD is only able to pass messages to handlers in scripts that have been successfully compiled without any errors. You can manually check for errors before exiting the Script Editor by selecting Compile from the Edit menu (or press F4). If there is an error, HyperPAD will assist you by positioning the cursor at the location of the error and displaying an error message. COMPILING WITH THE DEBUGGING SWITCH Runtime errors occur when something goes wrong in a script while browsing your pad. Normally, HyperPAD will take you to the offending script so that you can correct the problem. With larger scripts that contain many handlers, it may be difficult to locate the source of a runtime error. _______________________________________________________________________ Chapter 2: PADtalk Scripts 22 ________________________________________________________________________ To assist you in locating runtime errors, you can turn on the Debug option on the Edit menu. When you compile the script with the Debug option on, HyperPAD includes line number information with the compiled code. Then, following a runtime error, HyperPAD places the cursor directly on the line in which the error occurred. If you compile with the Debug option off and a runtime error occurs, HyperPAD simply places the cursor at the top of the offending script. THE COMPONENTS OF A SCRIPT A script consists of handlers, which you were introduced to above, and functions, which will be introduced in this section. HANDLERS As you have learned, a handler is a portion of a script that is invoked when a specific message is received by the object that contains it. Each handler names the message it responds to and includes some action(s) to be taken when that message is received. Here is a more complex handler. It receives two parameters from the statement that calls it. handler calcResult(i,j); begin put i * j / 100 into the message box; end; Sometimes, you may want a handler to receive a variable number of parameters. In this case, it is necessary to know how many parameters were passed to your handler and what each of them are. This is accomplished using the functions param, paramCount, and params. These functions return information about the number of parameters that were passed to your handler, the entire parameter list, and what each parameter is. The following function sums its parameters and returns the total to the calling statement. function addNums; begin put 0 into total; for i = 1 to the paramCount do add param(i) to total; return total; end; Notice that this example doesn't declare any parameter variables. Instead, it accesses the parameters using the param function. _______________________________________________________________________ Chapter 2: PADtalk Scripts 23 ________________________________________________________________________ DEFINING YOUR OWN FUNCTIONS In addition to handlers, scripts can contain your own functions. A function is a group of statements that returns a single value. Functions can be called from other handlers in the same script, or from scripts higher in the message hierarchy. For example, the following function asks a question in a dialog box using the answer command, then returns the result to the caller using the return statement. function okToContinue; begin answer "Is it safe"; return it; end; The return statement defines the number or text value that the function will return to the calling statement. The return statement will not stop execution of the handler (only exit and pass stop the execution of a handler). If you specify more than one return statement, the last return statement executed will determine the returned value of the function. Calling your own functions is just like calling HyperPAD's built-in functions. The following statements call the function defined above: put okToContinue() into res; if okToContinue() is "Cancel" then beep; put "You selected" & okToContinue(); The open and close parenthesis are used to distinguish a function call from a message name. The statement okToContinue; is a message name that gets sent to the current script, where as okToContinue() calls the user-defined function. _______________________________________________________________________ Chapter 2: PADtalk Scripts 24 ________________________________________________________________________ The following example function counts the number of Bs in a passed parameter. function countBs(str); begin put 0 into total; for i = 1 to the length(str) do if char i of str is "B" then add 1 to total; return total; end; To call this function: put 5 + countBs("Bobby and Billy when out."); OTHER DEFINITIONS The following definitions are intended to introduce you to other PADtalk components used when writing scripts. COMMANDS Commands are statements that tell HyperPAD what to do. Each command ends with a semi-colon. For example: go to page 1; put "wow" into page field 1; HyperPAD's built-in commands are discussed in Chapter Eleven. CONSTANTS A constant is any named value that can't be changed. Unlike a variable, you can not alter a constant, and unlike a literal, its value is not always identical to its name. The following tables summarize HyperPAD's constants and their corresponding values. _______________________________________________________________________ Chapter 2: PADtalk Scripts 25 ________________________________________________________________________ MISCELLANEOUS CONSTANTS The miscellaneous constants are: Constant: Description: ---------------------------------------------------- empty Empty String "" false Boolean value false true Boolean value true pi The mathematical constant 3.14159 up Returned by ctrlKey(), altKey(), and shiftKey() down Returned by ctrlKey(), altKey(), and shiftKey() CHARACTER CONSTANTS The character constants are: Constant: Description: ---------------------------------------------------- formfeed ASCII 12 linefeed ASCII 10 quote ASCII 34(") return ASCII 13 space ASCII 32(" ") tab ASCII 9 _______________________________________________________________________ Chapter 2: PADtalk Scripts 26 ________________________________________________________________________ PROPERTY CONSTANTS The property constants are: Constant: Used with this property: ---------------------------------------------------- centered align checkBox style even parity fat cursor layer tabbing left namePosition, align listBox style none parity odd parity off cursor, printer, mouse on mouse, printer opaque style position tabbing right align scrolling style thin cursor top nameposition transparent style NUMERIC CONSTANTS The following constants can be used in place of any number to enhance readability of your scripts. The numeric constants are: zero three six nine one four seven ten two five eight _______________________________________________________________________ Chapter 2: PADtalk Scripts 27 ________________________________________________________________________ LITERALS A literal is a number or text string enclosed in quotes. The following are literals: 10 17.39 "hello" Special codes can be inserted into quoted text strings for characters that you can't easily type with the keyboard. Each code is started with the caret (^). The following table shows the supported codes and lists some examples: Code: Value: ---------------------------------------------------- ^^ ^ ^" " ^f formfee (ASCII 12) ^n linefeed (ASCII 10) ^t tab (ASCII 9) ^r carriage return (ASCII 13) ^d ASCII character n (where n is the 3 digit character number) ^x ASCII character n (where n is the hex character number) Examples: "The quick brown ^"fox^" jumped over the lazy dog" "^rThis is a new line" "square character ^d254 inserted here" "hex ^xf4 insert here" _______________________________________________________________________ Chapter 2: PADtalk Scripts 28 ________________________________________________________________________ FUNCTIONS HyperPAD contains many built-in functions, each of which return a single value. Some functions require you to pass some parameters. The following are a few of HyperPAD's built-in functions: min(10,12) time() files("*.DOC") HyperPAD's functions are discussed in Chapter Thirteen. PROPERTIES Properties are values that control how objects look and behave. All objects of the same type have the same properties, but each object has its own values for these properties. Color, for example, is a property of buttons. All buttons have the color property and all buttons may be a different color. The following are properties: lockText insertPoint hilite Object properties are discussed in Chapter Twelve. CONTAINERS A container is a storage place for a value. The following are containers: fields variables the message box selectedText Containers are discussed in Chapter Four.